feat(api): MCP OAuth discovery on /mcp (RFC-0044 phase 1) - #152

What

Phase 1 of RFC-0044 (#144, accepted 2026-11-08): OAuth discovery for remote MCP clients, behind a new McpMountOptions.oauth option (issuer, resource, optional scopesSupported, resourceName, documentation).

• /mcp 401 answers WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp", scope="…" (RFC 9728 §5.1, RFC 6750), with error="invalid_token" when a bearer was presented. The JSON body is unchanged.
• The RFC 9728 document is served at the path-aware form and at the root (the fallback clients probe), cacheable for an hour; scopes_supported is scopesForMode("edits"), the minimal set, as the RFC decides.
• Step-up: a token principal (new optional Principal.grantId, set by phase 2) calling a tool whose scopes the token lacks but the member's role holds gets 403 insufficient_scope with every missing scope in one challenge, decided from the static tool policy table before the JSON-RPC handler runs. Keys are never challenged (they cannot re-authorize), nor is a scope the role lacks (the client would loop).
• The /mcp route moved from createApi to packages/api/src/mcp-mount.ts; createApi shrank from 217 to 188 lines and the size baseline is tightened.
• Shared suite src/testing-mcp-oauth.ts on better-sqlite3 and Miniflare D1 (test/mcp-oauth.test.ts): challenge, invalid_token, both documents, bare 401 without the option, step-up for a grant principal, no challenge for a Contributor's grant or for an agent key. route-scopes.test.ts declares the two well-known routes.
• ADR-0004 addendum: "No OAuth provider" now points at RFC-0044. Changeset: patch for @cloudhal/api and @cloudhal/agent-runtime.

Not wired into the admin Worker or cloudhal studio yet: a deployment that sets the option would advertise an issuer whose metadata does not exist until phase 2 (the Better Auth authorization server). Phase 2 also needs cloudhal studio --base-url (#143).

Checklist

• pnpm check and cargo test --workspace pass locally — ran pnpm lint (Biome 2.6.2, error level), tsc --noEmit for @cloudhal/api and @cloudhal/agent-runtime, node scripts/size-check.ts, and vitest run test/mcp-oauth.test.ts test/route-scopes.test.ts test/agent-key-auth.test.ts (24 tests, both backends). The full suites were not run on the owner's machine by request; CI runs them.
• Contract change? pnpm gen was run and generated files are committed (docs/adr/0001) — n/a
• User-visible change in a published package? pnpm changeset added
• Commits are signed off (git commit -s, DCO)
• Docs / AGENTS.md updated if behaviour or commands changed — ADR-0004 addendum; AGENTS.md unchanged (no command changed)

🤖 Generated with Claude Code